Docs Content Updates#185
Open
skarim wants to merge 5 commits into
Open
Conversation
skarim
force-pushed
the
skarim/docs-content-updates
branch
from
July 23, 2026 22:36
93b07ff to
22033fa
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Stacked PR documentation for current merge behavior, terminology, APIs, webhooks, and CI guidance.
Changes:
- Standardizes “stack map” terminology and merge guidance.
- Adds REST and GraphQL API references.
- Expands webhook, stack metadata, and CI optimization documentation.
Show a summary per file
| File | Description |
|---|---|
docs/astro.config.mjs |
Adds API reference pages to navigation. |
docs/src/content/docs/index.mdx |
Updates homepage terminology and merging guidance. |
docs/src/content/docs/introduction/overview.md |
Clarifies stack merging behavior. |
docs/src/content/docs/guides/ui.md |
Standardizes stack map terminology. |
docs/src/content/docs/guides/stacked-prs.md |
Revises practical merging instructions. |
docs/src/content/docs/faq.md |
Expands metadata and CI guidance. |
docs/src/content/docs/reference/webhooks.md |
Documents stack fields and stacked events. |
docs/src/content/docs/reference/rest-api.md |
Adds the Stacks REST API reference. |
docs/src/content/docs/reference/graphql-api.md |
Adds the read-only GraphQL reference. |
Review details
- Files reviewed: 9/9 changed files
- Comments generated: 5
- Review effort level: Medium
| run: echo "Lowest unmerged PR in the stack" | ||
|
|
||
| - name: Run for the top PR in the stack | ||
| if: github.event.pull_request.stack.position == github.event.pull_request.stack.size |
| run: echo "Lowest unmerged PR in the stack" | ||
|
|
||
| - name: Run for the top PR in the stack | ||
| if: github.event.pull_request.stack.position == github.event.pull_request.stack.size |
|
|
||
| ## Example | ||
|
|
||
| Read a pull request's stack, its position, and every pull request in the stack: |
|
|
||
| ### The stack resource | ||
|
|
||
| The list, get, create, add, and unstack endpoints all return the stack resource: |
| ### Merging Stacks | ||
|
|
||
| The entire stack does not need to be merged at once, but PRs must be merged **from the bottom up**. GitHub supports two merge methods: | ||
| You can merge your entire stack, a single PR, or a portion of the stack spanning multiple PRs. When you click **Merge** on any PR, that PR **and every unmerged PR below it land together in a single atomic operation**. So you can: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Batch of updates to the Stacked PRs docs site.
Overview of updates
Clarified how merging works
Standardized terminology
Expanded the webhooks reference
stackobject. Documented the completestackobject on thepull_requestpayload:id,number,size,position(1 = bottom), andbase(ref,sha).stackedevent. Added a section for thepull_requestevent with thestackedaction, which fires when a PR is added to a stack, including its top-levelstackobject.stackfields to gate workflow steps — for example, running CI only for the lowest unmerged PR or the top PR of a stack.Added a REST API reference page
stackobject on pull requests. Documented that pull request resources include astackobject on both the detail and list endpoints, with a field table and thenullbehavior for standalone PRs.pull_requestfilter), get, create, add, and unstack — including request bodies, status codes, and the stack resource shape.Added a GraphQL API reference page
stackandstackEntryfields on thePullRequesttype, and thePullRequestStack,PullRequestStackEntry,PullRequestStackEntryConnection, andPullRequestStackEntryEdgeobjects, with a sample query. These are read-only — there are no stack mutations. Added the page to the Reference sidebar.Updated the FAQ
number,size,position,base) with examples, and cross-linked the webhooks and REST API references.Pages touched